home *** CD-ROM | disk | FTP | other *** search
/ Die Speccy' 97 / Die Speccy' 97.iso / amiga_system / the_aminet / comm / bbs / wwbbs31_source.lha / WWBBS / Programming / Messages.doc < prev    next >
Text File  |  1995-06-20  |  9KB  |  236 lines
  1. Using message functions in wwbbs.library
  2. ---
  3. To access a message database, you must first open the database with the
  4. function:
  5.  
  6.      APTR OpenMessageGroup(BYTE *path,BYTE *name,LONG type)
  7.  
  8. For the path and name fields, put in the path and name of the message base
  9. you wish to access, prepending the path with "MessageBases", and optionally
  10. including a slash.  For the type field, this will be either SHARED_LOCK or
  11. EXCLUSIVE_LOCK, which is defined in one of the dos header files.
  12. SHARED_LOCK means that you only want to read data from the database, while
  13. EXCLUSIVE_LOCK means that you want to read and/or write data from the
  14. database.  You must not try to write to a group that you only have a
  15. SHARED_LOCK on.  The functions returns a pointer to the group which you
  16. will use when calling the other functions.
  17.  
  18. You can also open the email database by giving a NULL for path and name.
  19.  
  20. Some examples:
  21.  
  22.      If you wish to open the message area "The Jungle" with a shared lock,
  23.      use:
  24.  
  25.           APTR group;
  26.           group=OpenMessageGroup("MessageBases","The Jungle",SHARED_LOCK);
  27.  
  28.      If you wish to open the message area "Amiga/Programming" with an
  29.      exclusive lock use:
  30.  
  31.           APTR group;
  32.           group=OpenMessageGroup("MessageBases/Amiga","Programming",
  33.                EXCLUSIVE_LOCK);
  34.  
  35.      If you wish to open the email area with a shared lock use:
  36.  
  37.           APTR group;
  38.           group=OpenMessageGroup(NULL,NULL,SHARED_LOCK);
  39.  
  40. Just to be on the safe side, you should only open one group at a time in a
  41. program.
  42.  
  43. After you are done with a database, call the function:
  44.  
  45.      void CloseMessageGroup(APTR group);
  46.  
  47. For example, "CloseMessageGroup(group);".
  48.  
  49. ---
  50.  
  51. After opening a database, there are four functions you can call to access
  52. the information in the database.  They are tag based:
  53.  
  54.      ULONG GetMessageTags(APTR group,Tag tag,...); /* gets message info */
  55.      ULONG SetMessageTags(APTR group,Tag tag,...); /* sets message info */
  56.      ULONG AddMessageTags(APTR group,Tag tag,...); /* adds a new message
  57.           record */
  58.      ULONG RemMessageTags(APTR group,Tag tag,...); /* removes a message
  59.           record */
  60.  
  61. Note that a companion function exists for each of these:
  62.  
  63.      ULONG GetMessage(APTR group,struct TagItem *tags);
  64.      ULONG SetMessage(APTR group,struct TagItem *tags);
  65.      ULONG AddMessage(APTR group,struct TagItem *tags);
  66.      BOOL RemMessage(APTR group,struct TagItem *tags);
  67.  
  68. Each message record in a database has a unique ID number which is a ULONG.
  69.  
  70. ---
  71.  
  72. ULONG GetMessageTags(APTR group,Tag tag,...); /* gets message info */
  73.  
  74. GetMessage() gets message information.  It returns the number of tags that
  75. were successfully processed.
  76.  
  77. These are the tags you can use:
  78.  
  79.      MSGTAG_ID
  80.           This tag must be present.  Here you specify the message id number
  81.           of the message you want to get information about.
  82.      MSGTAG_Exists
  83.           Use this tag when you want to know whether a message record
  84.           exists for the MSGTAG_ID that you specify, and when this is the
  85.           only tag you want to specify.  You must set it to TRUE.
  86.      MSGTAG_Thread
  87.           Use this tag to get the number of the thread to which this
  88.           message belongs.  Pass a (ULONG *), a pointer to a ULONG.
  89.      MSGTAG_From
  90.           Use this tag to get the name of the user who wrote the message.
  91.           Pass a (BYTE **), a pointer to a string.  You get a
  92.           null-terminated string with a maximum of 32 chars.  The pointer
  93.           you get back is valid until you call CloseMessageGroup().
  94.      MSGTAG_To
  95.           Use this tag to get the name of the user that the message is
  96.           addressed to.  Usage is the same as MSGTAG_From.
  97.      MSGTAG_Subject
  98.           Use this tag to get the subject of the message.  Usage is the
  99.           same as MSGTAG_From, except that this string has a maximum size
  100.           of 64 chars.
  101.      MSGTAG_Date
  102.           Use this tag to get the date that this message was written.  Pass
  103.           a (struct DateStamp **), a pointer to a pointer of a struct
  104.           DateStamp.  The pointer you get back is valid until you call
  105.           CloseMessageGroup().
  106.      MSGTAG_Text
  107.           Use this tag to get the message text.  Pass a (BYTE **), a
  108.           pointer to a string.  What you get is a pointer to a string of
  109.           the entire message text, with lines being separated by '\n', and
  110.           the entire string terminated by a NULL.  The pointer you get back
  111.           is valid until you call CloseMessageGroup().  If you get back a
  112.           NULL, then that means there is no message text.
  113.  
  114. ---
  115.  
  116. ULONG SetMessageTags(APTR group,Tag tag,...); /* sets message info */
  117.  
  118. SetMessage() sets message information.  It returns the number of tags that
  119. were successfully processed.
  120.  
  121. These are the tags you can use:
  122.  
  123.      MSGTAG_ID
  124.           This tag must be present.  Here you specify the message id number
  125.           of the message you want to "set".
  126.      MSGTAG_ForceSave
  127.           Use this tag when you want to force the system to save the
  128.           current database to file.  Note that whenever a change is made to
  129.           a database file, it is automatically saved to disk, so when you
  130.           use this tag it should be the only one present.  You must set it
  131.           to TRUE.
  132.      MSGTAG_DontSave
  133.           Use this tag when you want to postpone saving of the current
  134.           database.  You would want to do this if you are performing
  135.           several changes to a database, and instead of saving after each
  136.           action, it would be better to wait until you are done and then
  137.           "force a save" with MSGTAG_ForceSave.  You must set it to TRUE.
  138.      MSGTAG_Thread
  139.           Use this tag to set the number of the thread that this message
  140.           belongs to.  Pass a ULONG.  Normally you would not want to set
  141.           the thread number as it is automatically set by AddMessage().
  142.      MSGTAG_From
  143.           Use this tag to set the name of the user who wrote the message.
  144.           Pass a null-terminated string, max 32 chars long.
  145.      MSGTAG_To
  146.           Use this tag to set the name of the user to whom this message is
  147.           addressed.  Pass a null-terminated string, max 32 chars long.
  148.      MSGTAG_Subject
  149.           Use this tag to set the subject of the message.  Pass a
  150.           null-terminated string, max 64 chars long.
  151.      MSGTAG_Date
  152.           Use this tag to set the date of the message.  Pass a (struct
  153.           DateStamp *).  Normally you would not want to set the date, as it
  154.           is automatically set by AddMessage().
  155.      MSGTAG_Text
  156.           Use this tag to set the message text.  Pass a (BYTE *), a
  157.           null-terminated string.  In that string, you can separate lines
  158.           with a '\n'.
  159.  
  160. ---
  161.  
  162. ULONG AddMessageTags(APTR group,Tag tag,...); /* adds a message record */
  163.  
  164. AddMessage() adds a new message record.  It returns the message id number
  165. so you can make a subsequent call to SetMessageTags() and easily pass along
  166. the id in MSGTAG_ID.
  167.  
  168. Note that when a new message record is added, the MSGTAG_Thread and
  169. MSGTAG_Date are automatically set while everything else is initialized to
  170. NULL.
  171.  
  172. These are the tags you can use:
  173.  
  174.      MSGTAG_DontSave
  175.           Use this tag when to want to postpone saving of the current
  176.           database.  You would want to do this if you are performing
  177.           several changes to a database, and instead of saving after each
  178.           action, it would be better to wait until you are done and then
  179.           "force a save" with MSGTAG_ForceSave.  You must set it to TRUE.
  180.      MSGTAG_ReplyTo
  181.           Use this tag when you want this message to belong to the same
  182.           thread as another message.  Pass the message id number (a ULONG).
  183.  
  184. ---
  185.  
  186. BOOL RemMessageTags(APTR group,Tag tag,...); /* removes a message record */
  187.  
  188. RemMessage() removes a message record.  It returns either TRUE or FALSE,
  189. depending on whether or not the operation was successful.
  190.  
  191. These are the tags you can use:
  192.  
  193.      MSGTAG_ID
  194.           This must be present.  Here you specify the message id number.
  195.      MSGTAG_DontSave
  196.           Use this tag when to want to postpone saving of the current
  197.           database.  You would want to do this if you are performing
  198.           several changes to a database, and instead of saving after each
  199.           action, it would be better to wait until you are done and then
  200.           "force a save" with MSGTAG_ForceSave.  You must set it to TRUE.
  201.  
  202. ---
  203.  
  204. There are two more functions that you may find useful.  They are:
  205.  
  206. ULONG GetNextMessage(APTR group,ULONG message_id);
  207. ULONG GetPreviousMessage(APTR group,ULONG message_id);
  208.  
  209. Simply pass any number of message_id, and it will look for the
  210. next/previous message that exists, and it will return its message_id.  The
  211. message_id that you pass does not have to exist.
  212.  
  213. For example,
  214.  
  215.      To get the message id that comes after message #10:
  216.  
  217.           {
  218.             ULONG id;
  219.             id=GetNextMessage(group,10);
  220.            }
  221.  
  222.      To get the id of the first message in the database:
  223.  
  224.           {
  225.             ULONG id;
  226.             id=GetNextMessage(group,0);
  227.            }
  228.  
  229.      To get the id of the last message in the database:
  230.  
  231.           {
  232.             ULONG id;
  233.             id=GetPreviousMessage(group,~0);
  234.            }
  235.  
  236.